.\" runfile.8
.\" wcm, 2009.12.11 - 2009.12.15
.\" ===
.TH runfile 8 "January 2013" "runtools-2.07" "runtools"
.SH NAME
runfile \- run a program as specified in an argvfile
.SH SYNOPSIS
.B runfile [\-hV]
.I argvfile
.B [
.I args ...
.B ]
.SH DESCRIPTION
.B runfile
runs a program according to the arguments taken from
.IR argvfile .
.PP
An
.I argvfile
is a plain text file with one or more non-empty lines.
Each line read is taken as an individual element of an argument vector
for a program.
The first element of this argument vector
is required and should name the executable that
.B runfile
will run.
Any additional
.I args
given on the command line will be appended to the arguments
taken from
.IR argvfile .
.PP
.B runfile
trims any leading and/or trailing whitespace from each line read from
.IR argvfile .
Empty lines and lines beginning with the `#' character are ignored.
.PP
If
.I argvfile
is given as a
.RB ` - '
character,
the
.I argvfile
specification will be read from stdin.
.PP
The first element read from the
.I argvfile
will be taken as the executable that
.B runfile
will run
(that is, argv[0]).
If this element does not contain a ``/'' slash character,
.B runfile
will perform a shell-like search for the executable using the
.B PATH
variable in the current environment.
.SH OPTIONS
.TP
.B \-h
Help.
Print a brief usage message to stderr and exit.
.TP
.B \-V
Version.
Print the version number to stderr and exit.
.SH EXIT STATUS
.B runfile
exits with one of the following values:
.TP
0
The program given in
.I argvfile
was invoked and completed successfully.
In this case,
the exit code is returned by the
program,
rather than by
.B runfile
itself.
.TP
100
.B runfile
failed because of a usage error,
such as an invalid command\-line option or argument.
In this case,
.B runfile
prints a brief error message and usage help to stderr on exit.
.TP
111
.B runfile
failed due to some system or resource error.
In this case,
.B runfile
prints a brief diagnostic message to stderr on exit.
.TP
1\-127
The program given in
.I argvfile
was invoked and failed with its own non-zero exit status.
.SH CAVEATS
In most cases,
the arguments specified in
.I argvfile
will not normally want to follow the shell\-protecting quoting conventions
as might otherwise be used
when running a program in a shell environment.
.SH AUTHOR
Wayne Marshall, http://b0llix.net/perp/
.SH SEE ALSO
.nh
.BR runtools_intro (8),
.BR runargs (8),
.BR runargv0 (8),
.BR runchoom (8),
.BR rundetach (8),
.BR rundeux (8),
.BR runenv (8),
.BR runlimit (8),
.BR runlock (8),
.BR runpause (8),
.BR runsession (8),
.BR runtool (8),
.BR runtrap (8),
.BR runuid (8)
.\" EOF
